{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Using OpenAI’s Web Search Tool with AG2\n",
    "\n",
    "OpenAI’s latest GPT models—such as `gpt-4.1` and `gpt-4o-suffix` support a powerful, built-in [`web_search_preview`](https://platform.openai.com/docs/guides/tools-web-search?api-mode=responses) tool that enables real-time web access.\n",
    "\n",
    "In this guide, you'll learn how to integrate and use `web_search_preview` within the AG2 framework.\n",
    "\n",
    "## Installation\n",
    "\n",
    "Install AG2 with the `openai` extra.\n",
    "   \n",
    "```bash\n",
    "pip install -U ag2[openai]\n",
    "```\n",
    "> **Note:** If you have been using `autogen` or `ag2`, all you need to do is upgrade it using:  \n",
    "> ```bash\n",
    "> pip install -U autogen[openai]\n",
    "> ```\n",
    "> or  \n",
    "> ```bash\n",
    "> pip install -U ag2[openai]\n",
    "> ```\n",
    "> as `autogen`, and `ag2` are aliases for the same PyPI package.\n",
    "\n",
    "You're all set! Now you can start using `web_search_preview` with AG2.\n",
    "\n",
    "## Imports"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from typing import Literal\n",
    "\n",
    "from pydantic import BaseModel\n",
    "\n",
    "from autogen import AssistantAgent, LLMConfig\n",
    "from autogen.tools.experimental.web_search_preview import WebSearchPreviewTool"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Using WebSearchPreviewTool\n",
    "\n",
    "Now let’s create a `WebSearchPreviewTool` that will search the web and return the OpenAPI specification for a desired API (e.g., GitHub, WhatsApp, etc.).\n",
    "\n",
    "The tool is configured to:\n",
    "- Search for a raw OpenAPI specification file in JSON or YAML format.\n",
    "- Return a structured response that matches the `OpenAPISpec` class, which includes:\n",
    "        - The source page where the spec was found.\n",
    "        - A direct URL to the OpenAPI file.\n",
    "        - A relevance score (1–5).\n",
    "\n",
    "This makes it easy to retrieve usable API definitions for further automated processing or integration."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "llm_config = LLMConfig.from_json(path=\"OAI_CONFIG_LIST\")\n",
    "\n",
    "agent = AssistantAgent(\n",
    "    name=\"assistant\",\n",
    "    llm_config=llm_config,\n",
    ")\n",
    "\n",
    "\n",
    "class OpenAPISpec(BaseModel):\n",
    "    source_url: str\n",
    "    openapi_spec_url: str\n",
    "    result_score: Literal[1, 2, 3, 4, 5]\n",
    "\n",
    "\n",
    "tool = WebSearchPreviewTool(\n",
    "    llm_config=llm_config,\n",
    "    instructions=\"\"\"Find a url with opeanapi specification for the wanted api. The specification must be in JSON or YAML format.\n",
    "I need a link to raw file (because I will use it in curl command).\n",
    "\n",
    "Output should be just:\n",
    "\n",
    "Source: <url> (where te openapi specification was found)\n",
    "OpenAPI Specification URL: <url>\n",
    "\n",
    "\n",
    "- make sure that the url which you found is not returning 4xx error, otherwise you will be penalized!\n",
    "- do not give up easily, try to find the url in different ways\n",
    "- do not use markdown [url](<url>) format\"\"\",\n",
    "    text_format=OpenAPISpec,\n",
    ")\n",
    "tool.register_for_llm(agent)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Start Searching\n",
    "\n",
    "This loop demonstrates how to automatically search for OpenAPI specifications for a list of popular APIs. For each API name, the assistant runs a web search using the configured `WebSearchPreviewTool`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "apis = [\"github\", \"whatsapp\", \"trello\", \"giphy\", \"pokemon\"]\n",
    "for api in apis:\n",
    "    response = agent.run(\n",
    "        message=f\"Let's find a url with openapi specification for {api}.\",\n",
    "        tools=agent.tools,\n",
    "        user_input=False,\n",
    "        max_turns=3,\n",
    "    )\n",
    "    response.process()\n",
    "    print(\"-\" * 40)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "front_matter": {
   "description": "Web Search Preview",
   "tags": [
    "tools",
    "search",
    "responses api"
   ]
  },
  "kernelspec": {
   "display_name": ".venv",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.11.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}
